클로드 코드 완벽 가이드 — 17장 인증 구현하기 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

17장에서 다루는 내용

• Supabase 설정하기 — BaaS 플랫폼 가입, 프로젝트 생성, 인증 Provider 설정
• Context7 MCP 연동하기 — 최신 라이브러리 문서를 클로드 코드에 제공하는 방법
• Supabase 인증 연동하기 — 클로드 코드를 활용해 이메일 로그인/회원가입 SSR 인증 시스템 구현

전체 흐름도

[Supabase 설정]          [Context7 MCP 연동]        [Supabase 인증 연동]
    |                        |                          |
    v                        v                          v
+-------------------+  +---------------------+  +---------------------------+
| 1. 가입 & Org     |  | 1. MCP 설치          |  | 1. 클로드에 계획 요청      |
|    생성            |  |    claude mcp add    |  |    (경계 명확히 설정)      |
| 2. 프로젝트 생성   |  |    context7          |  | 2. SSR 구현 계획 수립      |
|    (이름/비밀번호/ |  | 2. /mcp 명령으로     |  |    @supabase/ssr 패키지   |
|     리전 선택)     |  |    연결 확인         |  | 3. 작업 실행 지시          |
| 3. Email Provider |  +---------------------+  |    .env.local 설정         |
|    활성화          |       |                    |    클라이언트 유틸리티     |
|    Confirm Email  |       v                    |    미들웨어 설정           |
|    해제            |  최신 Supabase 문서를     |    인증 페이지             |
| 4. Connect 버튼   |  클로드가 직접 참조        |    Server Actions          |
|    URL/AnonKey    |                            |    콜백 처리               |
|    복사 저장       |                            | 4. .env.local 값 입력      |
+-------------------+                            | 5. 서버 재시작 & 확인     |
        |                                        +---------------------------+
        v                                                    |
  .env.local 파일에 저장                                     v
  NEXT_PUBLIC_SUPABASE_URL=<URL>               로그인/회원가입 동작 완성
  NEXT_PUBLIC_SUPABASE_ANON_KEY=<KEY>

선수 지식 체크리스트

• [ ] 16장: UI 프로토타이핑 (로그인/회원가입 페이지 시안 제작)
• [ ] Next.js App Router 기본 개념 (Server Components, Server Actions)
• [ ] 환경변수(.env.local) 사용법
• [ ] 쿠키 기반 세션 관리 개념

핵심 키워드

섹션 1: Supabase 설정하기

한 줄 요약

Supabase에 가입하고 프로젝트를 생성한 뒤, Email Provider를 활성화하고 연결에 필요한 URL과 Anon Key를 확보한다.

쉬운 설명 (비유)

Supabase는 "레고 백엔드 키트"와 같다.

직접 서버를 만드는 것 = 나무를 베고, 못을 깎고, 집을 짓는 것
Supabase를 쓰는 것 = 이미 만들어진 레고 블록을 조립하는 것

가입 → Organization(회사/팀) → 프로젝트(앱 하나) → 인증 설정
마치 아파트 단지에 입주하면서 동(Organization)과 호수(Project)를
배정받고, 현관 비밀번호(인증)를 설정하는 것과 같다!

실무 예제: Supabase 프로젝트 설정 단계별 안내

[1단계] 가입하기
  → supabase.com 방문 → Sign Up → Organization 생성
  → 이름: 아무거나, 종류: Personal, 플랜: Free

[2단계] 프로젝트 생성
  → New Project 클릭
  → Organization 선택 (방금 만든 것)
  → Project name: k-nomad (원하는 이름)
  → Database Password: Generate Password → Copy → 안전한 곳에 저장!
  → Region: Northeast Asia (Seoul) → Create new project

[3단계] Email Provider 설정 (약 10분 후 활성화 완료)
  → Authentication → Sign In / Providers → Email 선택
  → "Confirm Email" 토글 → OFF (개발용: 이메일 확인 없이 가입 가능)
  → Save

[4단계] 연결 정보 확보
  → 상단 [Connect] 버튼 클릭
  → App Frameworks 탭 → Next.js 선택
  → NEXT_PUBLIC_SUPABASE_URL 복사
  → NEXT_PUBLIC_SUPABASE_ANON_KEY 복사
  → .env.local 파일에 저장

핵심 체크포인트

• [ ] Supabase는 Firebase와 유사하지만 PostgreSQL 기반으로 SQL 유연성을 갖춘 BaaS 플랫폼이다
• [ ] Organization → Project 순서로 생성하며, Free 플랜으로 무료 사용 가능하다
• [ ] Database Password는 생성 시 반드시 복사해서 안전하게 보관해야 한다
• [ ] Confirm Email을 해제하면 이메일 확인 없이 회원가입이 가능해진다 (개발 편의용)
• [ ] Supabase 무료 이메일 발송은 시간당 2개로 제한되므로, 개발 중에는 Confirm Email을 끄는 것이 합리적이다
• [ ] Region은 사용자와 가까운 곳(서울)을 선택해야 성능이 좋다

섹션 2: Context7 MCP 연동하기

한 줄 요약

Context7 MCP를 클로드 코드에 설치하여 최신 라이브러리 문서를 자동으로 참조할 수 있게 한다.

쉬운 설명 (비유)

LLM의 문제: 학습 데이터에 최신 정보가 없을 수 있다!

Context7 MCP = "실시간 백과사전 도우미"

일반 LLM: 작년에 배운 교과서만 가지고 답변
Context7 연동 LLM: 최신 공식 문서를 실시간으로 찾아서 답변

예) Supabase가 올해 API를 바꿨다면?
  ❌ Context7 없이: 옛날 API로 코드 작성 → 에러
  ✅ Context7 있으면: 최신 공식 문서 참조 → 정확한 코드

실무 예제: Context7 설치 및 확인

# 1. Context7 MCP 설치 (Local Connection 방식)
claude mcp add context7 -- npx -y @upstash/context7-mcp

# 설치 성공 메시지:
# Added stdio MCP server context7 with command: npx -y @upstash/context7-mcp
# to local config

# 2. 연결 확인
# 클로드 코드에서 /mcp 명령어 실행
# context7 ✓ connected 체크 표시 확인

핵심 체크포인트

• [ ] LLM은 학습 데이터 이후의 최신 정보를 모를 수 있으므로, Context7 MCP로 최신 문서를 보완한다
• [ ] claude mcp add context7 -- npx -y @upstash/context7-mcp 명령으로 설치한다
• [ ] /mcp 명령으로 context7이 connected 상태인지 확인할 수 있다
• [ ] Context7 공식 깃허브: github.com/upstash/context7

섹션 3: Supabase 인증 연동하기

한 줄 요약

클로드 코드에게 경계를 명확히 지정한 프롬프트로 Supabase Auth SSR 인증 시스템을 구현하고, .env.local에 값을 입력하여 로그인/회원가입을 완성한다.

쉬운 설명 (비유)

인증 연동 = "건물에 출입 통제 시스템 설치하기"

1단계: 경비 회사에 설계도 요청 (클로드에게 계획 요청)
  → "이메일 로그인만, SSR 방식으로, 코드는 아직 쓰지 마"
  → 경비 회사가 "이렇게 설치하겠습니다" 계획서 제출

2단계: 계획 확인 후 시공 지시 (작업 실행)
  → "계획대로 하되, 절대 범위를 벗어나지 마"
  → 출입카드 시스템(미들웨어), 문 잠금장치(인증 페이지),
     방문자 기록부(콜백 처리)가 한 번에 설치됨

3단계: 열쇠 넣기 (.env.local에 값 입력)
  → 출입 시스템이 동작하려면 실제 열쇠(URL, Key)가 필요

실무 예제: 클로드 코드에게 인증 구현 지시하기

프롬프트 1: 계획 수립 요청 (경계 설정이 핵심!)

Supabase Auth를 연동하려고 해.
- 소셜 로그인은 추가하지 않을거야 이메일 로그인만 사용할 거야.
- SSR이 지원되는 형태로 계획을 알려줘.
- 실제 코드는 아직 작성하지 말고 어떻게 해야 하는지 알려주기만 해.
- context7을 사용해서 최신 Supabase 사용법을 알아봐줘.

클로드의 SSR 구현 계획 (핵심 구조):

1. @supabase/ssr 패키지 사용 - 최신 SSR 전용 패키지
2. Cookie 기반 세션 관리 - getAll/setAll 방식으로 쿠키 처리
3. Next.js 14 App Router 방식 - Server Components와 Server Actions 활용
4. Middleware 인증 보호 - 전역 인증 상태 관리

생성되는 파일 구조:

프로젝트/
├── .env.local                          ← Supabase URL/Key 설정
├── middleware.ts                       ← 전역 인증 보호 및 세션 갱신
├── src/
│   ├── utils/supabase/
│   │   ├── server.ts                   ← 서버 컴포넌트용 클라이언트
│   │   ├── client.ts                   ← 브라우저용 클라이언트
│   │   └── middleware.ts               ← 미들웨어용 세션 관리
│   ├── app/
│   │   ├── login/
│   │   │   ├── page.tsx                ← 로그인/회원가입 폼 (Server Actions)
│   │   │   └── actions.ts             ← 로그인/회원가입 서버 액션
│   │   ├── register/
│   │   │   └── page.tsx                ← 간소화된 회원가입 폼
│   │   ├── auth/callback/
│   │   │   └── route.ts               ← 이메일 확인 토큰 처리
│   │   └── error/
│   │       └── page.tsx                ← 에러 페이지
│   └── components/
│       ├── auth/UserMenu.tsx           ← 사용자 메뉴 컴포넌트
│       └── layout/Header.tsx           ← 헤더에 사용자 상태 통합

프롬프트 2: 작업 실행 지시

현재 계획한 플랜을 기반으로 작업을 실행해줘.
우리 계획을 벗어나는 작업은 절대로 하지 말고
작업이 끝나면 어떤 작업들을 했는지 분석해서 알려줘.

클로드가 수행한 작업 목록:

1. 환경 설정
   - .env.local 파일 생성 (Supabase URL/Key 설정)

2. 의존성 설치
   - @supabase/supabase-js, @supabase/ssr 패키지 설치

3. Supabase 클라이언트 유틸리티
   - src/utils/supabase/server.ts - 서버 컴포넌트용 클라이언트
   - src/utils/supabase/client.ts - 브라우저용 클라이언트
   - src/utils/supabase/middleware.ts - 미들웨어용 세션 관리

4. Next.js 미들웨어
   - middleware.ts - 전역 인증 보호 및 세션 갱신

5. 인증 페이지
   - src/app/login/page.tsx - 기존 UI를 Server Actions 방식으로 변경
   - src/app/register/page.tsx - 간소화된 회원가입 폼으로 변경

6. Server Actions
   - src/app/login/actions.ts - 로그인/회원가입 서버 액션

7. 콜백 처리
   - src/app/auth/callback/route.ts - 이메일 확인 토큰 처리
   - src/app/error/page.tsx - 에러 페이지

8. 사용자 세션 확인
   - src/components/auth/UserMenu.tsx - 사용자 메뉴 컴포넌트
   - src/components/layout/Header.tsx - 헤더에 사용자 상태 통합

핵심 체크포인트

• [ ] 클로드 코드에게 작업을 요청할 때 반드시 경계를 명확히 설정해야 한다 ("코드는 아직 쓰지 마", "범위를 벗어나지 마")
• [ ] @supabase/supabase-js와 @supabase/ssr 두 패키지가 함께 설치되어야 SSR 인증이 동작한다
• [ ] 서버/클라이언트/미들웨어 각각 별도의 Supabase 클라이언트 유틸리티가 필요하다
• [ ] .env.local 파일에는 민감한 정보(URL, Key)가 들어가므로 클로드 코드가 직접 수정하지 않을 수 있다 → 직접 입력해야 한다
• [ ] 환경변수 키 이름이 다르게 생성된 경우, 클로드 코드에 물어보면 올바른 키 이름을 알려준다
• [ ] Server Components에서 getUser()로 세션을 확인하고, 비인증 사용자는 자동 리다이렉트된다
• [ ] 서버 재시작했을 때 오류가 없으면 인증 연동 성공이다

연습문제

문제 1 (기본)

Supabase 프로젝트 생성 시 반드시 복사해서 저장해야 하는 값 2가지는 무엇이고, 각각 어디에 사용되는가?

문제 2 (중급)

클로드 코드에게 인증 구현을 요청할 때 "경계를 명확히 설정하라"고 강조하는 이유는 무엇인가? 구체적인 프롬프트 예시와 함께 설명하라.

문제 3 (심화)

SSR 인증에서 서버용(server.ts), 클라이언트용(client.ts), 미들웨어용(middleware.ts) Supabase 클라이언트를 각각 따로 만드는 이유를 설명하라. 하나로 통합하면 어떤 문제가 발생하는가?

부록 A: 용어 사전

부록 B: 비교표

Supabase vs Firebase

인증 구현 방식 비교

Supabase 클라이언트 유틸리티 비교

부록 C: 참고 자료